# Документы

В этой главе описывается, как правильно писать строки документации и как использовать все доступные функции scaladoc.
Scaladoc расширяет возможности Markdown дополнительными функциями, такими как ссылки на определения API. 
Это можно использовать из статической документации и постов в блогах для создания смешиваемого контента.

### Куда поместить строки документации

Комментарии Scaladoc идут перед элементами, к которым они относятся, 
в специальном блоке комментариев, который начинается с `/**` и заканчивается `*/`, например:

```dotty
/** Комментарий начинается здесь.
  * Левая "звезда", за которой следует пробел в каждой строке,
  * позволяет продолжить комментарий.
  *
  * Даже на пустых строках разрыва абзаца.
  *
  * Обратите внимание, что '*' в каждой строке выровнена
  * со вторым '*' в '/**' так, чтобы
  * левое поле находилось в том же столбце, где
  * первая строка и последующие.
  *
  * Комментарий закрывается с помощью '*' и обратного слэша.
  *
  * Если используются теги Scaladoc (@param, @group и т.д.),
  * не забудьте поместить их в отдельные строки без предшествующих им строк.
  *
  * Например:
  *
  * Рассчитать квадрат заданного числа
  *
  * @param d the Double to square
  * @return the result of squaring d
  */
 def square(d: Double): Double = d * d
```

В приведенном выше примере комментарий Scaladoc связан с методом `square`, 
поскольку он находится в исходном коде прямо перед ним.

Комментарии Scoladoc могут идти перед полями, методами, классами, трейтами, объектами. 
На данный момент scaladoc не поддерживает прямое решение для документирования пакетов. 
На гитхабе есть специальный [issue](https://github.com/lampepfl/dotty/issues/11284), 
где можно проверить текущий статус проблемы.

Для первичных конструкторов класса, которые в Scala совпадают с определением самого класса, 
тег @constructor используется для указания комментария, 
помещаемого в документацию первичных конструкторов, а не в обзор класса.


### Теги

Scoladoc использует теги `@<tagname>` для предоставления определенных подробностей полей в комментариях. 
Теги включают:

#### Теги, специфичные для класса

- `@constructor` помещенный в комментарий класса, будет описывать первичный конструктор.

#### Теги, специфичные для метода

- `@return` для детализации возвращаемого значения из метода (по одному на метод).

#### Теги метода, конструктора и/или класса

- `@throws` какие исключения (если есть) может генерировать метод или конструктор.
- `@param` детализация параметра метода или конструктора, 
предоставляется по одному `@param` для каждого параметра метода/конструктора.
- `@tparam` детализация параметра типа для метода, конструктора или класса. 
Указывается по одному для каждого параметра типа.

#### Теги использования

- `@see` ссылки на другие источники информации, такие как ссылки на внешние документы или связанные объекты в документации.
- `@note` добавление примечания о предварительных или последующих условиях или любых других заметных ограничениях или ожиданиях.
- `@example` предоставление примера кода или соответствующей документации.

#### Теги группировки

Эти теги хорошо подходят для больших типов или пакетов со многими элементами. 
Они позволяют организовать страницу Scoladoc в отдельные разделы, 
каждый из которых отображается отдельно в выбранном порядке.

Эти теги не включены по умолчанию! 
Необходимо передать флаг `-groups` в Scaladoc, чтобы включить их. 
В sbt это обычно выглядит примерно так:

```sbt
Compile / doc / scalacOptions ++= Seq(
  "-groups"
)
```

Каждый раздел должен иметь идентификатор из одного слова, 
который используется во всех этих тегах, как показано ниже в `group`. 
По умолчанию этот идентификатор отображается как заголовок раздела документации, 
но можно использовать `@groupname`, чтобы указать более длинный заголовок.

Как правило, необходимо поместить `@groupprio` (и, возможно, `@groupname` и `@groupdesc`) в Scaladoc 
для самого пакета/trait/класса/объекта, описывая все группы и их порядок. 
Затем поместить `@group` в Scoladoc для каждого члена, указав, в какой группе он находится.

Члены, у которых нет тега `@group`, будут перечислены в результирующей документации как "Ungrouped".

- `@group <group>` - пометить сущность как члена `<group>` группы.
- `@groupname <group> <name>` - указание необязательного имени для группы. 
`<name>` отображается как заголовок группы перед её описанием.
- `@groupdesc <group> <description>` - добавление необязательного описания для отображения под именем группы. 
Поддерживает многострочный форматированный текст.
- `@groupprio <group> <priority>` - управление порядком группы на странице. По умолчанию 0. 
Несгруппированные элементы имеют неявный приоритет 1000. 
Используются значения от 0 до 999, чтобы задать положение относительно других групп. 
Низкие значения появятся перед высокими значениями.

#### Другие теги

- `@author` - предоставление информации об авторе для следующего объекта.
- `@version` - версия системы или API, частью которой является этот объект.
- `@since` - похож на `@version`, но определяет систему или API, в котором эта сущность была впервые определена.
- `@deprecated` - помечает объект как устаревший, 
предоставляя как замену реализации, которую следует использовать, 
так и версию/дату, когда этот объект устарел.
- `@syntax <name>` - позволяет изменить парсер для docstring. 
Синтаксис по умолчанию — markdown, однако можно изменить его с помощью этой директивы. 
В настоящее время доступны синтаксисы `markdown` или `wiki`. Пример использования: `@syntax wiki`.

#### Макросы

- `@define <name> <definition>` позволяет использовать `$name` в других комментариях Scaladoc в том же исходном файле, 
который будет заменен на `<definition>`.

Если комментарий не предоставляется для объекта на текущем уровне наследования, 
но предоставляется для переопределенного объекта на более высоком уровне иерархии наследования, 
будет использоваться комментарий из суперкласса.

Аналогично, если `@param`, `@tparam`, `@return` и другие теги сущностей опущены, 
но доступны из суперкласса, эти комментарии будут использоваться.

#### Явный

Для явного наследования комментариев используется тег `@inheritdoc`.

#### Разметка

Scaladoc предоставляет два анализатора синтаксиса: `markdown` (по умолчанию) или `wikidoc`. 
В Scaladoc по-прежнему можно встраивать теги HTML (как и в Javadoc), 
но в большинстве случаев это не обязательно, поскольку вместо этого может использоваться разметка.

##### Markdown

Markdown использует [вариант commonmark](https://spec.commonmark.org/0.30/) с двумя пользовательскими расширениями:

- `wikidoc` - ссылки для удобства
- `wikidoc` - кодовые блоки с синтаксисом фигурных скобок

##### Wikidoc

Wikidoc — это синтаксис, используемый для scala2 scaladoc. 
Он поддерживается из-за многих существующих исходных кодов, однако не рекомендуется его использование в новых проектах. 
Синтаксис вики можно включить с помощью глобального флага `-comment-syntax wiki` 
или с помощью `@syntax wiki` директивы в строке документации.

Некоторые из стандартных доступных разметки:

```
`monospace`
''italic text''
'''bold text'''
__underline__
^superscript^
,,subscript,,
[[entity link]], e.g. [[scala.collection.Seq]]
[[https://external.link External Link]], e.g. [[https://scala-lang.org Scala Language Site]]
```

#### Другие примечания по форматированию

- Абзацы начинаются с одной (или нескольких) пустых строк. 
`*` на полях для комментария допустимо (и должно быть включено), но в противном случае строка должна быть пустой.
- Заголовки определяются окружающими символами `=` с большим количеством `=` для обозначающих подзаголовков. 
Например `=Heading=`, `==Sub-Heading==` и т.д.
- Блоки списка представляют собой последовательность элементов списка с одинаковым стилем и уровнем, 
без прерываний от других стилей блоков. 
Неупорядоченные списки можно маркировать с помощью `-`, 
нумерованные списки можно обозначать с помощью `1.`, `i.`, `I.` или `a.` для различных стилей нумерации. 
В обоих случаях должно быть дополнительное пространство впереди, а большее пространство создает подуровень.

Разметка для блоков списка выглядит так:

```
/** Вот неупорядоченный список:
  *
  *   - Первый элемент
  *   - Второй элемент
  *     - Подпункт ко второму
  *     - Еще один подпункт
  *   - Третий пункт
  *
  * Вот упорядоченный список:
  *
  *   1. Первый пронумерованный элемент
  *   1. Второй номер позиции
  *     i. Подпункт ко второму
  *     i. Еще один подпункт
  *   1. Третий пункт
  */
```


### Связывание с API

Scaladoc позволяет ссылаться на документацию по API с помощью ссылок в стиле Wiki. 
Связать с `scala.collection.immutable.List` так же просто, как `[[scala.collection.immutable.List]]`. 
Для получения дополнительной информации о точном синтаксисе см. [Ссылки](linking.md).


---

**Ссылки:**

- [Scaladoc Guide](https://docs.scala-lang.org/scala3/guides/scaladoc/docstrings.html)
